88 
. 
S38388328388838 


**F ILE**1D**SORLIB 


SSSSSSSS 
SSSSSSSS 


nunnn 
nnnno 


SSSSSS 
SSSSSS 


nnnn 
nunnn 


SSSSSSSS 
SSSSSSSS 


S8S8S88S8S 


E 
E 
E 
E 
E 
E 
E 
E 
E 
E 
E 
E 
E 
E 


MMMmMmMmMmMmMmmMmmMmmmmncn 


— 


bt 8 Pd Ot as bt be Os Ot Os 8 


ot Oo Ot Os Os be Ps Pe os 0 Ot es 
oe 


— 


—e 
be 
—_—e 
_— 


$$$, 


1 
SORLIB.REQ;1 16-SEP-1984 16:58:08.17 Page 1 


File: SORLIB.REQ IDENT = ‘V04-000' ! File: SORLIB.REQ Edit: PDG3034 


i eee eeeeeeeeeeeeeeeeeeeeeeeeeHeeeeeeeeeeeeeeeeeeeeeeeeeeerereeeeeeeeeeereeee 
'® 

‘® COPYRIGHT (c) 1978, 1980, 1982, 1984 BY 

'‘® DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASSACHUSETTS. 

'® ALL RIGHTS RESERVED. 


te THIS te Sethe 4 FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED 
tt ONLY IN ACCORDANCE WITH THE TERMS OF SUCH biC yt SE ~ A THE 
t* INCLUSION OF 1H Ne ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR OTHER 
tt COPIES THEREOF MAY re BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY 
:* QTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY 


® 
® 
& 
* 
® 
v 
® 
® 
® 
® 
ie TRANSFERRED. ® 
* 
® 
7 
® 
® 
* 
® 
* 
® 
® 


ie THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT 
i CORPORATION NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL E 


tt DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR _ RELIABILITY OF ITS 
:* SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. 


NOTICE 
QUIPMENT 


Vee RRR EEA AEA AEA AREER EAA AREA AEE 
' 


‘ee 


i FACILITY: VAX=11 SORT / MERGE 

i ABSTRACT: 
This is the common definition file for VAX-11 SORT / MERGE. 
ALL definitions of interest to more than one module are in this file. 
This file is used as a Library source. 


i ENVIRONMENT: VAX/VMS user mode 
i AUTHOR: P. Gilbert, CREATION DATE: 07-Dec-1981 
i MODIFIED BY: 


1 
' 
' 
' 
! 
' 
! 
| 
' 
1 
i 
' 
' 
t 
! 
' 
: 103-913 Original 

: 105-016 Add section on pad choracters and correct the extension for 

: specification fries Saenses PDG 13-Dec-1982 

! Lb a S44 Add wf NAMES wt of work tite. names. PDG 26-Dec-1982 
i 103- 18 Added BDB_ CHANG "eG ots Dec-1982 

! -01 poze gforee Tike description blocks (WFBs) distinct from DDBs. 

: 31-Dec-1982 

! 

' 

' 

i] 

! 

' 


10 ~839 Aga een reuse toee. net983 4-Jan-1983 

T 1 Add UB ~pEV te 6-J 

103-022 Removed” PI/ST_A R; added B S_DECM, WRK_SIZ. PDG 26-Jan-1983 

T03-0 Chenge $1 STAT “ORK USE te STAT T_K_WRK_ACQ, Added WFB_ =¥3 field. 
STREAR for stable merges. PDG 27-Jan 3 

103-086 Remove on emes on pad characters. Add COM_PAD. PDG 8-Feb-1983 

T03-025 Remove unreferenced fields. Change Linkage declarations so 
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L 
L 


register information is available to zoneve Y_SUB at run time. 


Define the macro SOR ~ ATAL. Pos 16-Mar-1983~ 
103-026 Give the SORSRO_CODE PSECTs the EXE. attr res 7-Apr-1983 
103-027 Information hiding of — ure structure. POG 12-Ap 
T03-028 Move definitions of fields specific to scretchei/e to SORSCRIO 


rom this module. PDG 1 Dg ge- 

703-029 eed COM Ra SGRATCH. oe B ae rie | 

C DG 1 ine 
703-031 Add COMA RCHFLAG. PDG™ “wee O79 9 
703-032 Add CoLt wae stuff. Pps fe 
703-0 Change TON_K_B UFSIZE, to 5b ca Piha r AXELN. 

Add s support ais tor ¥ AXELN. Jette East 
T03-034 Chenge HB to 


COM_RHB_INP and com RHB_OUT. 
s to avoid problems” withe merge, where an incoming 
record overwrites the VFC area for the outgoing record. 
PDG 24-Jul-1984 


IBRARY ‘SYSSLIBRARY: STARLET"; 
IBRARY ‘SYSSLIBRARY:XPORT'; 
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SOR 
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} XPORT 
' 
| The use of XPORT fousse ame problems, most notably with alignment, 
; and the default sign extension. The following macros are used. 
CRO 
XBYTE = SALIGN(BYTE) XEXPAND setts(#) z 
XWORD = SALIGN(WORD) ZEXPAND $B1TS(16) ‘ 
XLONG = SALIGN(FULLWORD) ZEXPAND $B1TS(32) %, 
XDESC = SALIGN(FULLWORD) $SUB_BLOCK(2) %, 
SALIGN(FULLWORD) SADDRESS %; 


XADDR = 
SSHOW (FIELDS) 


H 1 
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POSITION AND SIZE MACROS 


i 

i 

i 

MACRO 
} Macros used for field references 


Be ots nf 


og the fo construct a bit mask from a standard four-component field 
finition (offset, position, size, extension). The result has set 

ts in those positions that belong to the field. A List of field 
finitions can be specified. 


CRO 
B=0,9,1,0%; 


MASK_(A,B) is equal to %B8'1000111100' 
MASK_(O,P,S,EJ= 
(T *"CEPS4(S))) = (1 * (PD) &, 


MASK io 
TO OR XMASK_(ZREMAINING)) %, 


! Macros to align a specified value at the bit position specified by a 
! standard four-component field definition (offset, position, size, 
extension). A List of values and field definitions can be specified. 
i Example: 
CRO 
A=0,2,4,0%, 
B=0,9,1,0%; 
ALIGN_(7,A,1,B) is equal to 7*2 OR 1°9 
ALIGN _CV,0,P,S,EJ= 
CO) * fps) x, 


pe 


ALIGN C= 
(0 OR XALIGN_(ZREMAINING)) 2%; 
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GENERAL 
= . 
FALSE= 0; 
ELIF= ELSE IF %; 


Macro to round a value to the next higher multiple of a number. 


' 
! 
! The first parameter is the number which is to be rounded. 

! The second parameter is the multiple up to which we round. 

' f omitted, the default for the second perenater is ZUPVA 
The second parameter should be a Literal, and a power of 2. 
R 


OUND _(A,B) = 
2TF £NULL(B) 
ZTHEN (((A) * XUPVAL=1) AND NOT (X%UPVAL-1) 
XELSE (((A)+ (B)  =1) AND NOT ((B) =1) 


) 
) 


Macro to calculate floor(log2(constant)) 
LN2_(A)= 
(ZNBITSU(A)=1) 2%; 
: Macro to signal an internal consistency check. 
BUGCHECK (A)= 
BEGIN BUILT 
CHMU(ZREF (0 


IN CHMU; 
»); 


: Macro to establish a condition handler. 
ESTABLISH_(X) = 
BEGIN BUILTIN FP; 

FP = X; 


: Macro to produce a List of names 
PREFIX_(A)(B] = %NAME(A,B) %; 


3 


' 
. 
' 
. 
' 
. 
' 
+ 
' 
. 
' 
. 
' 
. 
! 
. 
' 
. 
' 
. 
' 
. 
' 
. 
' 
. 
' 
. 
' 
. 
' 
* 
' 
. 
' 
M 
' 
. 
' 
. 
' 
. 
' 
: 
' 
* 
' 
* 
' 
. 
' 
. 
' 
. 
' 
. 
' 
. 
1 
. 
' 
. 
' 
. 
' 
. 
' 
. 
' 
. 
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MACRO 
! Macros to determine if the value of an expression is one of a set of 
! specified ona’ }< integer values. These macros can be used only if the 
: following conditions are met: 
The value to be tested is in the range 0 through 127. 
The values to be tested for are all in the range 0 through 31. 
Example: 
: IF ONEOF_(.X, BMSK_(1,3,5)) ... 
! 


i The code generated is much more efficient than a series of comparisons 

} (provided that the parameters of BMSK_ are all compile-time constant). 

XBMSK_CAJ= 
ZTF (A) GTRU 31 XTHEN ZWARN('ONEOF won''t work’) %F1 
(1 * (31 = (A))) &, 


BMSK + 
TO OR XBMSK_(ZREMAINING)) %, 


ONEOF_(A,B)= 
(TBS * (A)) LSS 0) &; 


Macros to create initialized, read-only bit-vectors. 
The first parameter to BV_ is the largest element which will be 
accessed in the bit-vector. 


For example: 


OWN PRIMES: BV_( 51, 2,3,5,7.11,13,17,19,23,29,31,37,41,43,47,51 ); 
! IF .PRIMESC.1) 

THEN 2Z( I is Prime )% \ 
ELSE 2%( I is Composite )% 


BV_1_CAJ] = CA] = 1 &, 


BV_(M) = BITVECTOREM+1) 
PSECT(SORSRO_CODE) PRESET( BV_1_(ZREMAINING) ) %; 


MACRO 
! Macros to distinguish whether the value of an expression is amoun 
! one set of values, or another set of values, based on a single bit. 
: An error diagnostic is issued if a single bit will not suffice. 


DIST_(X,Y,2) = 
BEGIN 
LITERAL 


~ 


} Page 


1 
1 


:08 


16-SEP-1984 16:58 


— 
or 
So 
ive} 
[4 

© 
@ 
—_ 
“ 


— 
Oo 
ze 
~~ 
on 
2- 
<«~ 
— 
~u 
“~> 
-~o 
n= 
~w 
wa 
>pr 
~ 
f 
wns 
cr 
ren 
—_— ooo 
o 
= —II_ ISD 
-a& «woow 
“oe rMewwZ 
Qa tn ee ae aed 
aoe Jd 
aanwm wee ¢ 
O> ' Qe 
<~- 0 
w=fesee 
~~ ~o 
~ (waa 
> =< 
~w~ Can 
woe ene 
Pt el 4 2 
— ween 
ox re 
wo > 
areca 
rw ws 
we rw 
ove-a 
—~r verve 
- = ~~ 
” t 
-_ - 
a we, 
bl aw 
“ 
= 


6 OR DIST3 


( 
J = (X KOR Y) 


(X,ZREMAINING) + 0) %, 


— SS 
i 1 
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DEBUGGING CODE 


This section defines macros to aid in writing debugging code. 


The a aviation cnt used to Bs todd bean include compiler etebuaging 
code. $s e® - gbuggi ng code ate nc luded. 

false, wk a come is omi he macro DEB_CODE is provided to 
bracket debugging code that is” to be cnenotelanitie executed. 


In addition, the global variable "‘SORS$$D"' in the COMENTRY module can be 
ysed fo, obtain conditional execution it debugging code. This variable 
nitialized to zero, but may be a tered during the "initial DEBUG 


dialogue, before the compiler started 
DBG>D sonsson ye "oecesrrr® (for example) 
DBG>D SORS$D= (for example) 
DBG>G 
The bits in the variable "SORS$D"" are allocated as follows: 
0 - 944444 Dump = information 
1 %X*00000002' Dump sprrensaten statistics 
2 <x"00000006" Dump allocation information 
a) %X'40000000' —_ unassigned 
31 %x*80000000' Unassigned 


The macro DEB_SWITCH is provided to bracket conditionally executed 
debugging code. 


! Macro to bracket unconditional debuggin code. The parameter is an 
expression that will be compiled if &VARIANT is true. 


bee. See Ne 
Athen RIANT 


aFI i. 


! Macro to bracket conditional debugging code. The first parameter is 
' a bit number in the variable SORS and L.A, second parameter is an 
i expression that will be evaluated i if tha is set. The entire 
expansion is compiled only if ZVARIANT is true. 


DEB_SWITCH(A B)= 
ZIF XVARIANT 


N 
BEGIN EXTERNAL SORSSD; 
IF .SOR$$D<A,1> THEN B; 


RFI &, 


"1 
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; Macro to test an assertion about compile-time constants. 


ASSERT_(A)= 
iF NOT (A) 


N 
BEARORC" Assertion failed’) 


' 
! 
LITERAL 


LITERAL 


LITERAL 
LITERAL 


LITERAL 
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MAXIMUM VALUES 


X_KEYS= 255, ' Maximum 
MAX_FILES= 0, ! Maximum 
MIN-WORK_FILES= 1, i Minimum 
DEF -WORK_F ILES= ; ' Default 
MAX_WORK FILES= 10, ! Maximum 
MAX_MERGE_ORDER=1 ! Maximum 
MAX-SPC_LINE= 132, i Maximum 
MAX_SEQ_RECLEN= 72067. ! Maximum 

X_REL_RECLEN= 16384, ! Maximum 
MAX I1DX-RECLEN= 1g 84, i Maximum 
MAX_ISAMKEYLEN= 2 | Maximum 
MAX_REF SIZE= 65585 i Maximum 
MAXPSECTSIZE= 2147483647; i Maximum 
MIN_MBC= 7 ! Minimum 
MAX~MBC= 16, i Maximum 
MIN_MBF = 0, ! Minimum 

X_MBF = 2; ! Maximum 
DEF _FILE_ALLOC= 128*3, ! Default 
DEF-TRM_ALLOC= 16; ! Default 


COM_K_BPERPAGE= 512 
COM~K“BPERBLOCK= 512; 


' Define a Literal for the amount of work 
! for prestcseas tee text, and another for 
to al 


WRK_K_ALLOC= 128 * COM_K_BPERPAGE, ! 
WRK_K-COLLATE= 6 * 256; ! 


1 
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number of sort keys allowed 
number of input files. 
number of work files 

number of work files 

number of work files 

merge order 

length of spec file Line 


sequential file record length 
relative file record conet 

indexed file record Length 

index = data item length 

Length of a referenceable data-item 
Length of a PSECT 


MBC count 
MBC count (for RP06) 
MBF count 
MBF count 


file allocation 
allocation for terminals 


Bytes per page 
Bytes per Ask block 


space to allocate 
the amount of work space 


ocate if we only need to process a collating sequence. 


Allocation for work area 
Alloc to process collating sequence 


LIT 
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i 
} 
LITERAL 


INTERFACE VALUES 
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: Datatype values for use in the key definition buffer (KEY_BUFFER). 


KEY_K_CHAR= .. 
KEY_K “BIN = ¢° 
KEY-K~ZONE= . 
KEY “x “PACK= 4, 
KEY-K_USB= * 
KEY"K~DLO= 6, 
KEY-K-DLS= Fs 
KEY"K"DTO= 8, 
KEY-K"DTS= 9 

KEY"K"FLT= 16, 
KEY-K-FLID= 11, 
KEY"K~FLTG= 12. 
KEY"K"FLTH= 13, 
KEY_K_MAX= 133 

LITERAL 


TYP JK a?) ee 1, 
TYP_K TAG= ¢° 
TYP_K_INDEX= ° 
TYP_K ~ADDRESS= 4, 

“MAX= 4; 


1 

' 

These are also used to define the global Literals SORSGK_xxx_KEY. 
! These are used only for compatability purposes. 


Character data 

Signed Bay ot data 

Zoned decima 

Packed decimal 

Unsigned binary 

Decimal leading overpunch 
Decimal leading separate 
Decimal trailing overpunch 
Decimal trailing separate 


Floa ng 
D_floating 


Values for sort types, passed to SORSINIT_SORT. 
These are also used to define the global Literals SORSGK_xxx. 


Record sort 
sort 
ndex sort 


! Address sort 
! Maximum sort type 


i 
: 3 
i 
i 


! Options flags, passed to SORSINIT_SORT and SORSINIT_MERGE. 
These are used to define the global literals SORSV_xxx and SORSM_xxx. 


TYP7K 
MACRO 
i 
OPT_STABLE= 0. 0, 
OpT~ “EBCDIC= -, 
OPT—MU ‘ ¢° 
OPT“NO SIGNALS —@* 
OPT sea _CHECK= 0, 4. 
OPT SRODUPS= ‘6. 
OPT~ =F IXED= : 7. 
OPT"LOCATE= 4 0: 8: 
OPT “tOAD. FILL= 0, 9. 
LITERAL 


: Values to index the 


oy 
fe 
verve 
. 
- 


a et et st 
esse e888 

BS DE DS PL FL TL FL EL 
eee ee eee 
cmrmcace 


Stable sort 

EBCDIC collating sequence 
MULTINATIONAL collating sequence 
Don't signal errors 

Sequence check on merge input 


Delete records with Cups Ieate keys 
Records are fixed length (NYUsed 
Use locate mode with RETURN_REC 
Use LOAD_FILL on output le 


sort statistics 


1 
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| These are also used to define the global Literals SORSGK_STAT_xxx. 


SEQULST(STAT_K * Os Ve 
Address of ASCIC string for version number 
Records Input 
Records Sorted 
Records Output 
LRL for Input 
LRL of ee Length record 
LRL for Out —— 
Nodes in ee 
Initial d spereter runs 
Maximum merge order 
Number of merge passes 
Working=-set extent 
uerk t usage 
"8 wasage 


dh Tos 
Page faults 


rr 
we SvoOmLOH-Oue 


4 
Yevelsazss 


( 
( 
( 
( 
( 
( 
( 
( 
( 
( 
(MR 
( 
( 
( 
( 
( 
( 
( 
( 
( 
( 
( 
( 


j 
) 
) 
) 


(MAXTSTAT, 5); 
Define a single key description in the key description buffer 
SuNIT ce 


FIELDS = 
cer _TYPE= XWORD]J, ! Data type of k 
KBF_ORDER= XWORDJ, ! True iff deacentin order 
KBF_POSITION= XWORDJ, ! Offset to key within recoré (1..LRL) 
er LENGTH= CxWORDJ ! Length of key 
LITERAL 
aiid KBF_K_SIZE = $F IELD_SET_UNITS; ! Size in bytes 
KBF_BLOCK = XEXPAND SUNIT_BLOCK(KBF_K_SIZE) FIELD(KBF_FIELDS) 2%; 
: Define the key description buffer 
MACRO 
KEY_NUMBER = 9. 0, 16,02% ' Number of keys 
KEY-KBF(N) = + KBF_K SIZE * (N), 0, 0, 0%; 


STRUCTURE 
KEY Sew ae P,S,E;BS=MAX_KEYS] = 
eiiee *BS)] TKEY_BLOCK + 0) <P,S,E>; 
: Define the structure of a COLL_BLOCK, which is passed to SORSSPEC_FILE 


MACRO 


1 
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COLL_W_LENGTH = 9. - 16, 0%, ! Length of this block 
COLL-B"PAD = - O 8, 0%, 
COLL_A_PTAB = 4, 0, 32, %; 
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COMMON INFORMATION 


Information that must be available between calls to sort/merge is 
stored in a dynamically allocated data structure. The address of this 
data structure is stored in a context parameter snes ig passed to the 
sort/merge routines. If the context parameter is missing, the global 
variable SORSSCONTEXT is assumed to contain this pointer. 


COMPILET IME 

U_. = 0; 

recy F ZASSIGN(U__,U__ +1) ' i 

Le . + ! Macro to generate unique names 

XNAME ('U_*TENOMBER(U__)) %; , ; 

LITERAL 
OM_K_TREE= 13, ! Number of longwords for TREE_INSERT 
COM_K_SCRATCH= 10, ' Number of Longwords for SCRATCH_I0 
COM_K_CDD= 2; ! Number of longwords for CDD stuff 

SFIELD CTX_FIELDS = 
SET 
Routines 
COM_COMPARE= XADDRI, ! Address of user comparison routine 
COM_EQUAL= XADOR), ! Address of equal-key routine 
COM_INPUT= XADDR), ! Address of input conversion routine 
COM_OUTPUT= XADDR), ! Address of ouput routine 
COM_LENADR= XADDR), ! Address of length, address routine 
COM_NEWRUN= XADDRJ, ! Address of new run routine 
COM_ROUTINES= XDESCJ, ! A dymanic string descriptor 


Storage for TREE_INSERT 
.M_TREE_INSERT=C$SUB_BLOCK (COM_K TREE), ! Storage for TREE_INSERT 
Global sort information 


COM_CTXADR= XLONG), ! Address of users context longword 

COM_SORT_TYPE= (CXBYTE), ! Type of sort (TYP_K_RECORD,...) 

COM_NUM_FILES= KBVTEd. ! Number of input filés 

COM_WRK FILES= (XBYTEJ, ! Number of work files to use 

COM” STABLE= $B1TJ, ' Stable sort requested 

COM_SEQ CHECK= (S$BITJ, ' Sequence check 

COM~SIGRAL= $B1T), ' Sort/merge should signal errors 
COM_NOCHKPNT= $B81TJ, ! Checkpointing should not be done 
COM_LOAD FILL= (S$BITJ, ! Use load-fill on indexed files 
COM-NODUPS= $81T), ! Delete records with duplicate keys 
= $B1TJ, ! Use locate mode with RETURN_REC 


! 
Control flow flags 


COM_FLO_SORT= $B81T), ! May call Sort-Merge 

COM_FLO_NOINIT= (SBITJ, ! May not call Pass-Files, Init-Sort or Init-Merge 
COM_FLO_RELEASE=($81TJ, ! May call Release-Rec 

COM_FLO_RETURN= ($BITJ, ! May call Return-Rec or End-Sort 


Fi 
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'no way 
'no way 


Oh FL 8 pone neta seit . ! May call Do-Merge 

COM_FLO_ABORT= $B1TJ, ! May only call End-Sort 

Flags to amend for V3 compatability hacks 

COM_HACK_2ARGS= [$B1T], ! Pass only 2 args to callback routines 
COM_HACK _STRIP= $B1TJ, ! Strip the keys 


Merge-specific fields 
Note that COM_MRG_ORDER is non-zero iff this is a merge 


COM_MERGE= pesttz ! Indicates a merge (not a sort) 
COM_MRG_ORDER= XBYTES, ! Order of the merge 


; Spec text processing stuff 
COM_SPEC_TKS= CxwORD], 
Merge-specific fields 


COM_MRG_INPUT= KADDRI, 
COM_MRG_STREAM= CXLONG), 


Collating sequence stuff 


COM_COLLATE= XADDRI, 
COM_ST_SIZ= XLONG), 


Key information 


U_= XADDR, 
COM_SPEC_FILE= XADDRI. 
COM~TKS= XBYTEJ, 


Size of keys portion of internal node 


User-written merge input routine 
Stream number for stable merges 


Addr of get teting sequence routine 
Size (write-only 


Address of key descriptions 
Addr of structures from spec file 
Total key size (as specified by user) 


Override flags - ignore the specification text for these options 


COM_OVR_PROC= 
COM~OVR7KEY= 


Process specified 


$B81TI, ! 

VR_ $B81T), ! Key(s) specified 
COM_OVR_CHKSEQ= ($BITJ, ! Check sequence specified 
COM_OVR_STABLE= (SBITJ, ! Stable specifie 
COM_OVR_COLSEQ= ($BITJ, ' Collating sequence specified 
COM_BS_DECM= $B1T ! Base sequence was DEC_MULTINATIONAL 
U $81TS(4)), 
! Counts 


Et come FSUBRED 
COM_INP_ . 

: Collating sequence information 
COM_ Tle BREAK= ($8i73. 

Record format information 


Current number of runs 
Input record number (stable & stats) 


Indicates tie-breaking 
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COM _VAR= 
COM _MINVE C= 


COM. RHB_OUT= 


~ 
i) 
° 


>< >< >< 
oww 
<~< 
44 
mm 

Pee eee et ee et ae ae a ae 


ese seeseseses G& 


File information 


COM. INP” ARRAY= 


C_BpB= 


COM_PASS_FILES= XADDR 
OM~OUT_BpB= 


a 

Pa 

So 

_=J 

» 
ess ee 


XADDRJ, 


COM_FILE_ALLOC= CXLONG 
COM SP 


Statistics information 


com STAT arty XLONG] 


COM_STAT 


=RUNS D 
COM_STAT ~PASSES= XWORDJ, 
COM. STAT_MERGE= (XBYT 


: COM STAT_WS= 
: COM-STAT_VM= 


COM-OMI_RECNUM= CXLONGJ, 
COM_ —OUT_-RECNUM= CXLONG, 


Storage for 


tom. TREE_LEN= 
COM, TREE_ADR= 


i Scratch 1/0 


TREE_INSERT 


pr Oued 
XLONGJ 


information 
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Flag indicating variable Length input 


Length of VFC eres in internal node 
Length of COM_RHB buffer 
Number of different record, formats 
Longest input record pon ength 

pase tees record sree 

Length of internal format record 
Longest output record — 

Address of VFC area (input side) 
Address of VFC area (output side) 


Output file characteristics 
Address of output fi 7 . . 
Address of input file 

Address of current dhe sy file DDB 
Array of input DDB pointers 

File a lenet tan sore ' isd by user 
Address of spec file DDB 


(used only for statistics) 


! Number of nodes in sort tree 

i Number of runs from dispersion 
i Number of merge passes 

i Order of the merge 


! Maximum WS used 

! Maximum VM used 

' Number of omitted records (for stats) 
! Output record number (for stats) 


' Length of storage for tree 
! Address of storage for tree 


COM_SCRATCH_10= CS$SUB_BLOCK(COM_K_SCRATCH)], ! Storage for SCRATCH_IO 
! Locking information 


' COM_LOCKED= 


CXADDR), 


Specification file stuff 


COM_SPC_TXT= 


CxDESCI, 


) Specification file stuff 


com_ =f! ~$it= 
COM"KFT"SIZ= 
COM_ CFT sI2= 


XBYTE], 
XBYTEJ, 
XBYTEJ, 


' List of locked code sections 


! Dymanic string for spec file text 


SD 
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SORLIB.REQ;1 
con fot sits XBYTEJ, 
COM_TDOT_SiZ= XBYTEJ, 
COM_PAD= XBYTE ! Pad character 
U_= $817S(16)), 
COM_RDT_ADR= XADDRI, ! Record definition table 
COM_KFT_ADR XADORJ, ' Key/data syete ¢ 4p 
COM_CFT_AD XADDRJ, ! Constant i" ri 
COM_FDT_ADR XADDRJ, ! Field defin lon taple 
COM_TDT XADDRJ, : Test def nied on table 
COM-CONST_AREA= [XADDRJ, ' Constant arse (address) 
COM_PTAB= ADDR), ! Pointer to 256-byte table 
U_= XADDRJ, 
COM_WRK_SIZ= XLONGJ, ' Length of work area 
COM~WRK_ADR= XADDRJ, ! Address of work area 
COM ~WRK_END= XADDRI, ! Address past end of work area 


LITERAL 
MACRO 


UMESSAGE("CTX_K_SIZE = ', %NUMBER(CTX_K_SIZE 
UNDECLARE %QUOTE U_, U 


Other stuff 


éon _WORST= CXLONG], ! Worst error we've ever 
COM_WF _NAMES= ! conte List of indices into CFT of a file names 


CSBYTES(1+MAX_WORK_FILES)J, 
SALIGN(FULLWORD) 
COM_CDD= C$SUB_BLOCK(COM_K_CDD)), 


Additional storage for checkpoint stuff 

COM_COUNTDOWN= CXLONG), 

: Architectural flags (indicates which instructions are implemented) 
ol gemma CXLONG) 


! Storage for CDD stuff 


CTX_K_SIZE= SFIELD_SET_SIZE; 


CTX_BLOCK= BLOCKCCTX_K_SIZE) Fl 
CTXBLOCK_(S)= BLOCKCCTX-K-SIZE) FI 


! Size in Longwords 


D(CTX_FIELDS) 2%, 
D(CTX-FIELDS,S) 2; 


~ mm 


eef 
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RECORD FORMATS 


This section describes the various record formats that are used 
throughout Sort/Merge. 


INPUT RECORD FORMAT: 


VAR (@ word) is present only for variable length records 
VFC is present only for VFC files 
DATA is always present 


INTERNAL RECORD FORMAT: 


FORM KEY VAR VFC DATA STAB ! Record sort 
FORM KEY RFA FILE STAB ! Tag, address, index 


VAR (a word) is present only for variable length records 
VFC is present only for VFC files 

KEY is present for keys or converted keys 

FORM (a byte) is present only for multiple record formats 
FILE (a byte) is present only for multi-file non-record sorts 
STAB (a longword) is present only for stable sorts 

RFA (RABSS_RFA bytes) is present for non-record sorts 


OUTPUT RECORD FORMAT: 


VAR VFC DATA ! Record, tag sort 
RFA FIL ' Address sort 
RFA FILE OKEY STAB ! Index sort 


VAR (a word) is present only for variable length records 
VFC is present only for VFC f 

FILE (a byte) is present only for multi-file non-record sorts 
OKEY is the unconverted keys 

STAB (a longword) is present only for stable index sorts 


! Assertions can be made on the following Literals to determine the relative 
ordering of fields within a record. 


LITERAL 


_ORD_RFA = 0, ! RFA field 
COM_ORD_FILE = 1, ! File number field 
COM_ORD_FORM = ¢ ' Format field 
OM_ORD_OKEY = 3, ! Original keys (for index sorts) 
COM_ORD_STAB = 4, ! Stable longword fiel 
COM_ORD_KEY = 5, ! Key or converted key field 
COM_ORD_VAR = g. ' Length field 
COM_ORD_VFC = 7, ! VFC field 
COM_ORD_DATA = g. ! Data field 
COM_ORD_MAX = 9; ! Largest order value 


a 
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DEVICE DESCRIPTION BLOCK 


1 

i 

i The DDB contains information for ropetnesur itive a file. It does not 
: contain all RMS structures, since the FAB, NAM, and other erocks may 
; r 

' 


be discarded, thus decreasing the amount of virtual memory required. 
SUNIT_FIELD 
DDB_FIELDS = 
DDB_NEXT= XADDRI, ! Pointer to next DDB 
DDB_NAME= $SUB_BLOCK(2)], ! File name Length/address 
DDB_IFI= XLONG), ' Internal file identifier 
DDB_FOP= XLONG ! File options 
DDB-RAB_RAB= SBYTES(RABSC_BLN)J, i Record Access Block 
Peer Le XBYTE ! Input File number (0 on up) 
LITERAL 
DB_RAB= %F IELDEXPAND (DDB_RAB_RAB,O); 
UNDE CLARE 
DDB_RAB_RAB; 
LITERAL 
netne DDB_K_SIZE= SFIELD_SET_UNITS; ! Size in bytes 
DDB_BLOCK= ZEXPAND SUNIT_BLOCK(DDB_K_SIZE) FIELD(DDB_FIELDS) %; 


UMESSAGE("DDB_K_SIZE = ', %NUMBER(DDB_K_SIZE)) 


UNDE CLARE 
ZQUOTE SDESCRIPTOR; 


LINKAGES 


' 
' 
! 
; Several internal routines use JSB Linkages to improve 
4 Common Linkages are defined here. Linkages to externa 
: are defined as LNK_routine_name. 

L 


LITERAL 


COM_REG_SRC1 = 9 

COM“REG-SRC2 = 10, 

COMTREG-CTX = 11; 
MACRO 

ZPRESERVE(X) = XNAME(X,"_PR") X, 

XNOPRESERVE(X) = ZNAME(X.'"NP') 3. 

ANOTUSED (X) 2 INANE (X, *~ NU") &. 

XREGMASK cP = 1°P %, 

GMASK_C = 0 OR KREGMASK_(%REMAINING) %; 

KEYWORDMACRO 


JSB_DEFN_(NAM,PM,GL,PR,NP,NU) = 


LITERAL 
ZPRESERVE (NAM) = REGMASK_(ZREMOVE(PR)) + 0, 
ZNOPRESERVE(NAM) == REGMASK- (ZREMOVE(NP)) + 0. 
XNOTUSED (NAM) = REGMASK~(ZREMOVE(NU)) + 0; 
LINKAGE NAM = JSB(ZREMOVE(PM)): 
ZIF NOT ZNULL(GL) XTHEN GLOBAL(ZREMOVE(GL)) XFI 
ZIF NOT ZNULL(PR) 23TH HEN PRESERVE ( RE (PR)) %FI 
ZIF NOT ZNULL(NP) XTHEN NOPRESERVE(ZREMOVE(NP)) XFI 
. ZIF NOT ZNULL(NU) XTHEN NOTUSED(ZREMOVE(NU)) %FI 
JSB_DEFN. 
RAN = JSB OM_ INPUT 
Pm : els REG SRC1, REGISTERSCOM _REG_SRC2>, 
= 
- = ie 32 a pe ae 6. COM_REG_SRC1>, ' R6 holds the 
= 
GL = <8 _REG_CTX> ); 
JSB_DEFN_( 
RAM = y NE YRUN ! For COM_NEWRUN 
NU = 4.3 36 {o>, 
4 = <9:15, 
ee e630, REG_CTX> ); 
JSB_DEFN. ( 
un = JSB_COMPARE, 
= <REGISTER=COM_REG_ RCI 1 gReglTERCCOR, m REG. SRC we 
PR = <COM_REG_SRC1,COM~REG 
~f = . ° e 5 e ° e ' R Lt 299 
= e . ea eee 
GL = <CTXECOM_REG_CTX> ); é 
JSB_DEFN. ( 
RAM = JSB_OUTPUT ' For COM_OUTPUT 


PM = <REGISTER=COM_REG_SRC2>, 


K 1 
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er formance. 
routines 


variable Length 
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PR = F485 REG_SRC2>, 
+ "44 6 needed??? 
NP = ' R6 needed??? 
GL = <ttnceon’ “Ree. Te ); 
JSB_DEFN. ( 
RAM = JSB_EQUAL ' For COM_EQUAL 
=  cREGTSTER=COM_REG_SRC1 REGISTER=COM_REG_SRC2>, 
BR = <COM_REG_SRC1,COM-REG_SRC2>, 
ws 23'S 6.5.6.7,8 
= a o . 6 
GL = <CTx=COM{REG_CTX> ); 
JSB_DEFN, ( 
NAM = JSB_LENADR ! For COM_LENADR 
PM = <REGISTER=COM_REG_SRC2;REGISTER=0,REGISTER=1>, 
PR = <COM_REG_SRC2S, 
we NE 5.6.7.8,9 
= e ° e e 
GL = <Cfx=cOm:REGCTXx>’); 

JSB_DEFN. ( 
NAM = JSB_INSERT, ' For SORSSTREE_INSERT 
mn = ¢ _— D>, i Can we use registers??? 

= 
NP = <0,1,0,3,4,5.6,COM_REG_SRC1,COM_REG_SRC2>, 
GL = eetKeon’ REG “Ctx> J; 
JSB_DEFN, ( 
NAM = JSB_READIN ! For READ_INSERT 
PM = <R REGISTERSO. sREGISTER=8>. 
ee > » 3,3 6,9, 10>, 
= 
GL = <Cteceon’ “abe. orks ); 

JSB_DEFN_( 

RAM = JSB_EXTRACT, ! For SORSSTREE_EXTRACT 

mn = $3" TARD DARD>, i Can we use registers??? 
= 

NP = <0.1 "5 3,4,5,.6,COM_REG_SRC1,COM_REG_SRC2>, 

GL = <CTx=COm, née’ Cfx> 3; 7 = 

LINKAGE 

CAL_ACCESS = CALL ( STANDARD; ! For SORSSRFA_ACCESS 
REGISTER=0 
REGISTER=1 
GLOBAL (CTX= COM. REG_CTX); 
LINKAGE 


CAL_CTXREG = CALL: GLOBAL(CTX=COM_REG_CTX); 


a1 
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TUNING PARAMETERS 


' 
i 
i 
: These values are used to tune the sort. 
L 


ITERAL 
TUN_K_NONTREE = 192, ! Number of pages to not use for the tree 
TUN_K_FALLBACK = 64, ! Minimum pages for $reg for a large sort 
-KCALC_FI = TRUE, ! True to calculate FI in sort tree 
TUN_K_CALC FE TRUE, ! True to calculate FE in sort tree 
TUN_K_OUT_PREALL = TRUE ! True to preallocate output file 
TUN_K_WRK_PREALL = FALSE, i‘ True to preetiocate work files 
TUN_K_ALIGN_NODE = § ! Loge of alignment for nodes (longword align) 
TUN_K_ALIGN_TREE = 9, ! Logé2 of alignment for sort tree (page align) 
TUN_K_MRGCOST = 0 ! Cost of merge 
TUN_K_PURGWS = FALSE, i True to purge working set before INIT_TREE 
{ TUN_K_LCK_CTX = TRUE, ! True to lock context area in WS 
!  TUN_K_LCK_TREE = 3 ! Pages of tree to lock in WS 
! TUN_K_LCK CODE = TRUE, | True to lock code in wS 
TUN_K_BINMOVE = 3° ! Max number of bytes to move with binary moves 
nace Ene = 20; ! Maximum merge order for internal merges 
TUN_K_BUFSIZE = 
ZIF NOT HOSTILE_ELAN 
ZTHEN * COM_K_BPERPAGE ! Bytes in a buffer 
gel Se 5 * COM_K_BPERPAGE ! Bytes in a buffer 
LITERAL 


FUN_K_ CHECKPOINT = FALSE; ! True to gyrerete code for checkpointing 
ASSERT_TTON_K_MAX_MERGE GEQ MAX_MERGE_ORDER) 


%IF NOT FUN_K_CHECKPOINT 
, UNDECLARE XQUOTE COM_NOCHKPNT, XOUOTE COM_COUNTDOWN; 


STR 


SORLIB.REQ;1 
ERROR 
i 

i 

: value is o 

; 

i 

REQUIRE 'SRCS:SORM 

EThen XDECLARED (SORTS. FACILITY) 


LITERA 


N1 
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NUMBERS 


SORTS. FACILITY = SORS_FACILITY; 


UNDECLA 
SORS FACILITY; 


ACRO 
DEFSHR cHsg SEV) 
(SORE. SHR cuits 


ures: ste. iMSG),* + SORTS_FACILITY * 


LITERAL 
DEF SHR. ¢ 

BABLOGIC, pe yene 

CLOSEDEL, ERROR, 

CLOSEIN ERROR, 


CLOSEOUT, ERROR 
INSVIRMEM, SEVERE, 
OPENIN, SEVERE. 
OPENOUT, SEVERE. 
READERR, ERROR 
SYSERROR, SEVERE 


TEXT 
WRITEERR, ERROR): 


Internal logic error 
Error closing !AS 

Error closing iAS as 
Error closing !AS as 
Insufficient virtual 
Error opening !AS as 
Error opening !AS as 
Error reading !AS 

rx3tee service error 


Error writing !AS 


Each myosage issued has an associated literal value. The name of t 
the form "‘SORS_xxx"', where ‘'xxx"’ is the message tGenti fier. 


Other shared messages are defined in the SORCOMMAN module. 


16 %; 


detected 


input 
output 
memory 
input 
output 


! The fostoutog corte is used to diagnose an unrecoverable error, instead of 


: calling SOR$ 


CRO 
TT ae an 
RIF ZLENGT 


RROR directly. 


—aA 


= (RETURN S 
T STSSM_SEV 
H GTR 1 2THE 


° 


SERROR ( 
TY_OR thay S 


EVERE 
ZREMAINING 2FI)) %; 


MAC) 


ca 


TEXTUAL INFORMATION 
User-visible text is defined here. This text may be translated or 
changed, subject to the restrictions described below. 
Default file extension 
MACRO 


STR_DEF _EXT = ‘DAT’ %; 


Default specification file, and default specification file extension 


MACRO 
STR_DEF_SPECFILE = "SYSSINPUT' %, 
STR-SPC"EXT = ".SRT' %; 


These macroes define the external and internal representations of options for 
command Line qualifiers. The first parameter in each pair may be translated; 
the second, however, is used to define internal name for this option, and may 
not be translated. 


] 
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NUMB NUMB' ; 
"OVERPUNCHED_SIGN', ‘OVER’, 
*POSITION', "POSI", ! POSITION:nn 


ACRO 
STR_OPT_OUTFMT = ' outfile/FORMAT=(...) 
"FIRED', "FIXE', 
"VARIABLE', "VARI": 
"CONTROLLED", CONT. 
"BLOCK. SIZE", "BLOC' %, 
STR_OPT_INPFMT = ! inpfile/FORMAT=(...) 
' SIZE" "FILE', 
*RECORD_SIZE', "RECO' %, 
STR_OPT_PROCESS = ! /PROCESS=... 
"RETORD', "RECO', 
"TAG' "TAG' 
"ADDRESS', "apor', 
INDEX’, ‘INDE’ %, 
STR_OPT_KEY = ' /KEY=... 
"ASTENDING', "ASCE', 
"BINARY® BINA’. 
*CHARACTER', "CHAR', 
a am "DECI', 
"DESCENDING', "DESC’. 
"UNSIGNED ' "UNS"; 
"F_FLOATING', "FFL, 
"D-FLOATING', 'D7FL’. 
"G"FLOATING', 'GTFL', 
"H"FLOATING'. "H"FL'. 
"LEADING SIGN’, "LEAD, 
' R' UMB ! NUMBER:nn 
| 
| 
| 


— 
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"PACKED_DECIMAL', 'PACK', 
‘SI', n° hal ' SIZE:nn 
SIGNED’, 'SIGN', 
"SIZE" "SIZE", ! §I:nn 
"SEPARATE_SIGN', 'SEPA', 
"TRAILING-SIGN', 'TRAI', 
*ZONED', "ZONE" %, 
STR_OPT_COLL 
ASCII 
EBCDIC "EBCD', 


String passed to CLISGET_VALUE to get the command Line. 
iMACRO 
: STR_CLI_LLINE = ‘SLINE' %; 

FAO string used to output statistics via SYSSPUTMSG. 

The following text interacts closely with the code in PRINT_STATS. 


1 

i 

i 

! The text can, however, be changed (translated) independent of the code, if 

! the control string still uses the same FAO parameters, and text expands to 

' mo more than 1024 characters (a restriction of the uey that the text is 

: output), and Lines are separated by carraige-return/line-feed pairs. 

i Note that the use of tab character in the text is avoided, since 

some terminals may not have tab stops at multiples of eight. 

MACRO 

STR_STATS = XEXPAND ZSTRING( 
v4 518s VAX-11 SORT/MERGE !AC Statistics’, 
a eeerge reed, tide Input multiblock count: /O0L 
'/Records sorted: ! . *!10* Input mu ock count:! 
"'/Records output:!10UL', *!10* Output multiblock count: !5UL', 
‘i/Working set extent: !6UL", *!10* Input multibuffer count: !5UL", 
'/Virtual memory:!10UL', *!10* Output multibuffer count: !4UL", 

‘i /puf fered 170211 3ut ° site Rextnan perpe orders Teak te” 
i /Page faults: !i3UL",” ‘110* Number of neree passes: '6UL", 
"!/Sort tree size:!10UL", "110" Work file size used: !9UL', 
, {Elapsed time: !faxt', "17% Elapsed CPU:!6* !142T", 


' Logical names to use for work file ees lgnqents. 
: The n soa teal name actually used is: 
ZSTRING(STR_LOG_WORKFILE, (n=1)th character of STR_LOG_WORKNUM) 


MACRO 
STR_LOG_WORKFILE = "SORTWORK' %, 
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STR_LOG_WORKNUM = *0123456789ABCDEF GHIJKLMNOPQRSTUVWXYZ' %; 
H Default file name string to use for the work files. 
MACRO 

STR_DEF_WORKFILE = *SYSSSCRATCH:SORTWORK. TMP’ %; 


wn 
Po) 
— 


cr 
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CLEAN-UP ROUTINES 


Clean-up routines are con ler by SORSSEND_SORT. To facilitate 
information=hiding, the following mechanism is mers It allows 
each sub-system to declare a clean-up routine to clean up its data 
structures (so that SORSEND_SORT need not know the format of the 
data structures, or even the name of the clean-up routine). 


A clean-up routine is declared by: 
FORWARD ROUTINE CLEAN_UP; 
SORSSEND_ROUTINE_(CLEAN_UP); 
ROUTINE CLEAN_UP? CAL_CTXREG NOVALUE = ... 


SORSSEND_PSECT (X) = — XNAME(KEXACTSTRING(30,"_',*SORSRO_CODE'),X) %; 
SORSSEND-ROUTINE (xX) = 
NODEF AULT= ZEXPAND SORSSEND_PSECT_(2) (PIC, SHARE, NOWRITE EXECUTE); 
XNAME('_",X): | PSECT(XEXPAND SORSSEND~PSECT_(2)) 

INITIAL (X=%NAME('_ "| X)T 2; 


Fe 


rh —de 
—e 


= 


' 
4 
x 
% 
% 
' 
i 
L 


— 
— 
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MACRO 
MACRO 


ExEC-MODE VARIANT 


i) variant of Sort /Merge is made available to the RDMS group for 

use in EXEC mode. This is gotten by compiling the followin 

modules with the /VARIANT=1 command qualifier. Note that the /VARIANT 
ualifier will have no effect when compiling the cogy re files. 
xternal references from these modules are named SOR$Sfac$name. 

For example, the following code would be in SORINTERF. 


RIF HOSTILE 
THEN 


T_VM = SORSL 


E IBSGET_VM %, 

-_ REE_VM = SORSLIBSFREE_VM %; 

Another variant of Sort/Merge is made available for JRD on ELAN. 
This variant is gotten by compiling with /VARIANT=3. 

The major distinction between this and the previous is that 

the address of the context longword passed to Sort/Merge is passed 


to several of the SORSfac$name system services. 


The following modules are needed for these variants: 
COM.REQ, ve gee OPCODES.REQ, SORMSG.MSG, SORINTERF .B32, 
SORKEYSUB.B32, SORSORT.B32, SORSCRIO.B32, SORFILNAM.B32 


HOSTILE = ZVARIANT 2; 
HOSTILE_ELAN = (ZVARIANT AND %VARIANT*=1) &; 
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! End of SORLIB.REQ 


w¥k VAX/VMS V4.0 


